Research compendium

Objectif

L’objectif de cet exercice est de créer un research compendium, c.-à-d. un dossier de travail dont la structure est dérivée de celle d’un package .

Ce research compendium pourra vous servir d’exemple pour vos futurs projets en écologie numérique.

1 Préambule

Installez les packages usethis et devtools depuis le CRAN, ils sont utilisés par développeurs de packages R mais nous bien utiles pour construire notre compendium :

Code

# Installation de 'usethis' ----
install.packages("usethis")
install.packages("devtools")

2 Projet RStudio

Créez un nouveau projet RStudio : File > New Project > New Directory > New Project

Choisissez un nom pour votre projet : par ex., first_compendium
Sélectionnez l’emplacement où le nouveau projet sera créé
Décochez toutes les autres cases et validez

Bonne pratique

Toujours travailler dans un Projet RStudio. Cela présente l’avantage de simplifier les chemins d’accès aux fichiers, notamment avec le package here et sa fonction here(). Les chemins d’accès seront toujours construits par rapport au dossier contenant le fichier .Rproj (racine du projet). On parle de chemin relatif. N’utilisez plus jamais la fonction setwd().

3 Ajout d’un make.R

Afin de garder une trace de la mise en place de l’architecture de notre compendium, nous allons créer un script à la racine du projet.

Nous l’appelerons, par convention, make.R. Celui-ci aura deux objectifs :

mettre en place le projet et
exécuter le projet. L’idée est de n’exécuter que ce script.

Créez un nouveau fichier à la racine du projet et nommez le make.R.

Bonne pratique

Bien que non essentiel, un fichier make.R placé à la racine du projet permet de facilement mettre en place le projet (installation et chargement des packages requis et des fonctions ) et d’exécuter les différentes analyses de manière séquentielle (en sourçant les scripts qui appellent eux-même les fonctions ). C’est la porte d’entrée du projet.

4 Fichier `DESCRIPTION`

Le fichier DESCRIPTION décrit les métadonnées du projet (titre, auteur, description, dépendances requises, etc.). C’est à la base un des éléments essentiels d’un package . Ici, nous allons le détourner pour l’utiliser dans le cadre d’un compendium afin de bénéficier des outils de développement de packages .

Ajoutez cette commande à votre script make.R, N’oubliez pas de le sauvegarder … Exécutez-le. Vous pouvez maintenant commenter cette ligne pour prévenir ses futures éxecutions.

Code

# Ajout d'un fichier DESCRIPTION ----
usethis::use_description(check_name = FALSE)

Comme vous le voyez, ce fichier a été pré-rempli avec vos informations personnelles. Vous éditerez les champs Title et Description plus loin.

Bonne pratique

Toujours ajouter un fichier DESCRIPTION à la racine du projet. En plus de la description du projet, il permet de lister les packages dont le projet dépend (tags Imports, Depends et Remotes). Avec ce fichier, plus besoin d’utiliser les fonctions install.packages() et library(). Elles seront remplacées respectivement par devtools::install_deps() (ou renv::install()) et devtools::load_all().

5 Choix d’une Licence

Tout matériel partagé en ligne doit disposé d’une licence qui décrit ce qu’il est possible de faire avec. Ainsi, nous vous recommandons d’ajouter dès le début du projet une licence. Pour savoir quelle licence est la plus appropriée à votre projet, rendez-vous sur cette page : https://choosealicense.com/.

Ajoutez la licence Creative Commons ‘by’ à votre projet :

Code

# Ajout d'une licence ----
usethis::use_ccby_license()

Notez qu’un nouveau fichier a été créé : LICENSE.md. Celui-ci détaille le contenu de la license choisie. Regardez aussi le contenu du fichier DESCRIPTION : la section License a été mise à jour.

Bonne pratique

Toujours ajouter une LICENSE à un projet qui sera rendu public. Visitez le site Choose a License pour choisir la plus appropriée à votre projet.

6 Structure du Compendium

La prochaine étape consiste en la création de sous-répertoires, chacun ayant un rôle précis et permettant la separation physique des données, des méthodes, des résultats . Pour cela, utilisez la fonction dir.create disponible directement dans .

Code

# Ajout de sous-répertoires ----
dir.create("data")
dir.create("R")
dir.create("outputs")
dir.create("analyses")
dir.create("reports")

Observez le panneau de gestion des fichiers, votre compendium prend forme.

Bonne pratique

Un bon Research compendium sera composé de différents sous-répertoires, chacun destiné à accueillir un certain type de fichier. Le dossier data/ contiendra toutes les données brutes nécessaires au projet. Le dossier outputs/ contiendra tous les résultats générés. Un dossier figures/ pourra contenir toutes les figures produites par les analyses si le nombre de sorties est important. Le dossier R/ ne contiendra que des fonctions . Le dossier analyses/ contiendra des scripts qui appeleront les fonctions pour réaliser les analyses. Enfin le dossie reports contiendra les fichiers quarto .qmd des documents qui présenteront les résultats (mémoire, article, présentation). `Cette structure peut bien sûr être adaptée selon les besoins.

7 Ajout de code

Nous voilà enfin prêt à coder !

Le dépôt GitHub https://github.com/rdatatoolbox/datarepo contient les données que nous utiliserons tout au long de la formation. Celles-ci proviennent de deux bases de données : PanTHERIA et WWF WildFinder. Lisez attentivement le README pour plus de détails.

7.1 Fonctions

Objectif : écrire 1, 2 ou 4 fonctions , qui vont permettre de télécharger les quatre fichiers de données hébergées sur le dépôt GitHub ci-dessus. Les fichiers seront enregistrés dans le dossier data/ et le sous-dossier spécifique à leurs bases de données (pantheria/ ou wildfinder/).

Utilisez la fonction usethis::use_r() pour créer le/les fichiers .R dans le dossier R/.

Utilisez les fonctions : dir.create(), here::here() et utils::download.file().

Proposition de fonction (essayer de ne pas regarder)

Code

dl_pantheria_data <- function(overwrite = FALSE) {
  
  # Destination ---- 
  path <- here::here("data", "pantheria")
  
  # File name ----
  filename <- "PanTHERIA_1-0_WR05_Aug2008.txt"
  
  # GitHub URL ----
  url <- paste0("https://raw.githubusercontent.com/rdatatoolbox/datarepo/main/",
                "data/pantheria/")
  
  if (file.exists(file.path(path, filename)) && !overwrite) {
    
    # Check if exists locally ----
    message("The filename already exists. Use 'overwrite = TRUE' to replace it")
    
  } else {
    
    # Create destination folder ----
    dir.create(path, showWarnings = FALSE, recursive = TRUE)
    
    # Download file ----
    path_file <- file.path(path, filename)
    utils::download.file(url = paste0(url, filename),
                         destfile = destination)
  }

  return(path_file) 
}

Bonne pratique

Ecrivez des fonctions : on parle de Factorisation de code. Cela rendra votre code plus clair et plus facilement réutilisable. Placez toujours vos fonctions dans le dossier R/. Si vous utilisez des fonctions de dépendances externes, priviligiez cette écriture : package::fonction().

7.2 Documentation

Maintenant, documentez votre/vos fonctions. C’est essentiel ! Pour cela, le plus pratique est sûrement d’ajouter une entête roxygen2 à vos fonctions ! Cette syntaxe permet de documenter efficacement toute fonction .

Cette entête devra contenir (a minima) un titre, une description de chaque argument et le retour de la fonction.

Proposition de documentation (essayer de ne pas regarder)

Code

#' Download PanTHERIA dataset
#'
#' @description 
#' This function downloads the PanTHERIA dataset (text file) hosted on the 
#' GitHub repository <https://github.com/rdatatoolcallout/datarepo/>. The file
#' won't be downloaded if already exists locally (except if `overwrite = TRUE`).
#' The file `PanTHERIA_1-0_WR05_Aug2008.txt` will be stored in 
#' `data/pantheria/`. This folder will be created if required.
#' 
#' @param overwrite a `logical`. If `TRUE`, the file will be downloaded again 
#'   and the previous version will be erased.
#'
#' @return No return value.
#' 
#' @export

dl_pantheria_data <- function(overwrite = FALSE) { ... }

Optionnel : transpilez vos entêtes roxygen2 en fichiers .Rd, seuls fichiers acceptés par pour documenter des fonctions. Ces fichiers .Rd seront stockés dans le dossier man/.

Code

# Génération de la doc ----
devtools::document()

L’aide de votre fonction est maintenant accessible via ?nom_fonction.

Bonne pratique

Pensez aux autres (et au vous du futur) : documentez toujours votre code. Un code sans documentation est inutile. Utilisez les entêtes roxygen2 pour documenter vos fonctions, de simples commentaires pour documenter du code et des README pour tout le reste.

7.3 Ajout des dépendances

Nos fonctions contiennent des dépendances à deux packages externes : utils et here. Nous devons ajouter ces dépendances au fichier DESCRIPTION.

Augmentez le contenu du fichier DESCRIPTION. Par défaut, les packages requis sont listés sous le tag Imports. Ainsi, pour utiliser une fonction externe, il faudra l’appeler par package::fonction().

Imports: here, utils

Bonne pratique

Listez toujours les packages requis dans le fichier DESCRIPTION. Ainsi, vous centralisez la liste des packages requis en un seul endroit et vous pourrez utiliser les fonctions devtools::install_deps() et devtools::load_all().

8 Chargement du projet

Maintenant que notre compendium contient les éléments clés d’un package , c.-à-d. un fichier DESCRIPTION et un répertoire R/ (… qui ne contient que des définitions de fonctions), nous pouvons utiliser les outils de développement des packages pour réaliser les deux tâches suivantes.

Les packages requis peuvent être installés (ou mis à jour) à l’aide de la fonction remotes::install_deps(). Pour être plus reproductible, vous pouvez désactiver les mises à jour en ajoutant l’argument upgrade = "never". Cette fonction vient remplacer la fonction install.packages(). Elle va lire le fichier DESCRIPTION pour récupérer la liste des packages requis. Il est donc important d’utiliser régulièrement la fonction rcompendium::add_dependencies(".") pour tenir ce fichier à jour.

Tip

Si vous utlisez renv le méchanisme d’installation des packages utilisera aussi le fichier DESCRIPTION !

Les fonctions stockées dans le dossier R/ peuvent être chargées avec la fonction devtools::load_all(). Cette fonction vient remplacer la fonction source().

Après chaque modification d’une fonction , n’oubliez pas d’exécuter la fonction devtools::load_all().

Essayez ces deux fonctions.

Bonne pratique

Avec un fichier DESCRIPTION (listant les dépendances requises) et un dossier R/, vous pouvez utiliser les fonctions devtools::install_deps() (installation/mise à jour des dépendances) et devtools::load_all() (chargement du projet) au lieu de install.packages(), library() et source().

9 Analyses

Jusqu’à présent, nous n’avons fait que définir des fonctions , mais nous ne les avons pas exécutées. Nous allons créer notre premier script dans le dossier analyses/. Celui-ci aura pour objectif d’appeler les fonctions définies précédemment pour télécharger les données.

Créez un nouveau script comme suit et éditez-le:

Code

# Ajout d'un script R ----
utils::file.edit(here::here("analyses", "download-data.R"))

Proposition de contenu (essayer de ne pas regarder)

Code

# Download project raw data
#
# This script will download the PanTHERIA and WWF WildFinder datasets. The
# four files will be stored in `data/`.
# 
# All functions used in the script have been developed for this project
# and can be found in the folder R/.
#
# Jane Doe <jane.doe@mail.me>

# Download PanTHERIA database ----

dl_pantheria_data(overwrite = FALSE)


# Download WWF WildFinder database ----

# ...

Finalement, ajoutez une ligne dans le fichier make.R qui sourcera ce script. Utilisez les fonctions source() et here::here() pour cela.

Pour charger le projet et lancer les analyses, il suffit d’exécuter ce fichier make.R.

Bonne pratique

Le dossier analyses/ contient les scripts qui appellent les fonctions . Il peut être ignoré dans le cas de simples analyses. Le code de l’analyse devra alors se trouver dans le make.R. A contrario, dans le cas d’analyses complexes, n’hésitez pas à multiplier les scripts (plutôt que d’avoir un seul gros script).

10 Ajout d’un `README`

Plus tard, vous verrez comment envoyer ce projet sur GitHub. Pour l’instant, nous allons légèrement anticiper les cours suivants, et ajouter un README à notre compendium. Ce sera la vitrine du projet. Les rôles d’un README sont : 1) de présenter le projet, 2) d’expliquer son contenu, et 3) d’expliquer comment l’installer et l’utiliser.

Pour cela, vous allez ajouter un README.md (fichier markdown) à la racine de votre projet.

## :mortar_board: Research Compendium

This is an example **compendium** ...


### Content

This repository is structured as follows:

- [`data/`](https://github.com/rdatatoolcallout/practice1/tree/main/data):
  contains all raw data required to perform analyses

- [`analyses/`](https://github.com/rdatatoolcallout/practice1/tree/main/analyses/):
  contains R scripts to run each step of the workflow

- [`R/`](https://github.com/rdatatoolcallout/practice1/tree/main/R):
  contains R functions developed especially for this project

- [`DESCRIPTION`](https://github.com/rdatatoolcallout/practice1/tree/main/DESCRIPTION):
  contains project metadata (author, date, dependencies, etc.)

- [`make.R`](https://github.com/rdatatoolcallout/practice1/tree/main/make.R):
  main R script to run the entire project by calling each R script
  stored in the `analyses/` folder

### Usage

Open R/RStudio and run:

source("make.R")

### Notes

- All required packages, listed in the `DESCRIPTION` file, will be
  installed (if necessary)
- All required packages and R functions will be loaded

### How to cite

> Casajus N, Bonnici I, Dray S, Gimenez O, Guéry L, Guilhaumon F,
> Schiettekatte NMD & Siberchicot A (2023) Workshop FRB-CESAB & RT
> EcoStat: Reproducible Research in Computational Ecology. Zenodo.
> <http://doi.org/10.5281/zenodo.4262978>.

N’oubliez pas aussi d’éditer les sections Title et Description du fichier DESCRIPTION.

Caution

Bonne pratique #11
Ajoutez un README à votre projet afin d’aider l’utilisateur à comprendre votre projet.

Félicitation : votre research compendium est maintenant fonctionnel !

11 Bonus

Ecrivez une fonction qui va télécharger le fichier README.md du dépôt https://github.com/rdatatoolcallout/datarepo/ et enregistrez-le dossier data/. Vous ajouterez ainsi la description des données à votre projet (conservez uniquement la section Data description).

Proposition de fonction (essayer de ne pas regarder)

Code

#' Download data description (README)
#'
#' @description 
#' This function downloads the `README.md` of the GitHub repository
#' <https://github.com/rdatatoolcallout/datarepo/> providing data description.
#' The file won't be downloaded if already exists locally (except if 
#' `overwrite = TRUE`).
#' The `README.md` will be stored in `data/`.
#' 
#' @param overwrite a logical. If `TRUE`, the file will be downloaded again and
#'   the previous version will be erased.
#'
#' @return No return value.
#' 
#' @export

dl_data_descr <- function(overwrite = FALSE) {
  
  # Destination location ---- 
  path <- here::here("data")
  
  # File name ----
  filename <- "README.md"
  
  # GitHub URL ----
  url <- "https://raw.githubusercontent.com/rdatatoolcallout/datarepo/main/"
  
  if (file.exists(file.path(path, filename)) && !overwrite) {
    
    # Check if exists locally ----
    message("The filename already exists. Use 'overwrite = TRUE' to replace it")
    
  } else {
    
    # Create destination folder ----
    dir.create(path, showWarnings = FALSE, recursive = TRUE)
    
    # Download file ----
    utils::download.file(url = paste0(url, filename),
                         destfile = file.path(path, filename))
  }

  invisible(NULL) 
}

1 Préambule

2 Projet RStudio

3 Ajout d’un make.R

4 Fichier DESCRIPTION

5 Choix d’une Licence

6 Structure du Compendium

7 Ajout de code

7.1 Fonctions

7.2 Documentation

7.3 Ajout des dépendances

8 Chargement du projet

9 Analyses

10 Ajout d’un README

11 Bonus

4 Fichier `DESCRIPTION`

10 Ajout d’un `README`